/*
 * Course:    CS 590 Web Services
 * Semseter:  Spring 2009
 * Professor: Sedlemeyer
 * Project:   CHEAT (Code Help Educational Assignment Tool)
 * Due Date:  May 1, 2009
 * Team:      Sarcasm
 *            (Baker, Jason; Mitchell, Robin; Shie, Keith)
 */
package cheat.assignment;


import cheat.entities.AssignmentProperty;
import cheat.entities.Course;
import cheat.entities.License;
import javax.ejb.Local;


/**
 * Provides the local interface to the AssignmentManagerBean.
 *
 * The assignment manager contains the functionality related to
 * assignment management.
 *
 * @author Keith Shie
 */
@Local
public interface AssignmentManagerLocal {

  /**
   * Ensures that the specified License is in persistent storage.
   *
   * <p>First attempts to locate an existing License based upon the
   * url.</p>
   *
   * <p>If no such License can be found, one is created.</p>
   *
   * <p>Ideally, this method would not be part of a public API.  However, we
   * need to gain control over the transaction so that we can force the
   * persistance layer to generate the PK for the underlying License
   * Entity.  Providing this method as part of the public API is the most
   * straight forward way to gain this control.</p>
   *
   * @param url License url
   * @param description License description
   * @return Reference to License entity within persistent storage.
   */
  License ensureLicense( String url, String description );


  /**
   * Saves out the core part on an Assignment.
   *
   * <p>Ideally, this method would not be part of a public API.  However, we
   * need to gain control over the transaction so that we can force the
   * persistance layer to generate the PK for the underlying AssignmentProperty
   * Entity.  Providing this method as part of the public API is the most
   * straight forward way to gain this control.</p>
   *
   * @param assignment <p>core part of the assignment to be saved.
   * The object passed in should not contain references to other entities
   * which have their our requirement to gerenate a PK.</p>
   * @return The AssignmentProperty which has been saved.
   */
  AssignmentProperty saveAssignment( AssignmentProperty assignment );

  /**
   * Ensures that the specified Course is in persistent storage.
   *
   * <p>First attempts to locate an existing Course based upon the
   * label.</p>
   *
   * <p>If no such Course can be found, one is created.</p>
   *
   * <p>Ideally, this method would not be part of a public API.  However, we
   * need to gain control over the transaction so that we can force the
   * persistance layer to generate the PK for the underlying License
   * Entity.  Providing this method as part of the public API is the most
   * straight forward way to gain this control.</p>
   *
   * @param label Course label
   * @param description Course description
   * @return Reference to Course entity within persistent storage.
   */
  Course ensureCourse( String label, String description );
}
